fix: authentication error log on agent gateway integration - #267

Disclaimer: Do not include SAP-internal or customer-specific information in this PR (e.g. internal system URLs, customer names, tenant IDs, or confidential configurations). This is a public repository.

Description

When the Destination Service returns an auth token with a non-empty error field (e.g. "No consumed apis matching provided resource parameter found."), the Agent Gateway LoB flow previously raised a generic "Empty auth header" error with no indication of the underlying cause.

This fix surfaces the Destination Service error message directly in the raised exception:

• Adds error: Optional[str] field to the AuthToken dataclass, populated from the "error" key in the Destination Service v2 API response.
• Updates AuthToken.from_dict to raise DestinationOperationError with the Destination Service error message when a token carries an error field alongside empty type/value/http_header.
• Since the error now surfaces at parse time (inside Destination.from_dict), it propagates naturally through get_destination to the caller without any special handling in the Agent Gateway layer.

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update
• Code refactoring
• Dependency update

How to Test

1. Configure a destination whose token service returns a failure (e.g. a mismatched resource parameter causing "No consumed apis matching provided resource parameter found.").
2. Invoke the Agent Gateway LoB flow (fetch_system_auth or fetch_user_auth).
3. Observe that the raised exception now includes the exact error message from the Destination Service instead of a generic "Empty auth header" message.

Alternatively, run the unit tests:

uv run pytest tests/destination/unit/test_models.py::TestAuthTokenModel tests/agentgateway/unit/test_lob.py::TestFetchAuthToken -v

Checklist

• I have read the Contributing Guidelines
• I have verified that my changes solve the issue
• I have added/updated automated tests to cover my changes
• All tests pass locally
• I have verified that my code follows the Code Guidelines
• I have updated documentation (if applicable)
• I have added type hints for all public APIs
• My code does not contain sensitive information (credentials, tokens, etc.)
• I have followed Conventional Commits for commit messages

Additional Notes

The error field is part of the Destination Service OpenAPI spec for authTokens but was previously not modelled in AuthToken. The fix is fully backward-compatible: tokens without an error field parse as before, and AuthToken.error defaults to None. Tokens that carry a non-empty error alongside empty required fields now raise DestinationOperationError at parse time with the service-provided message included.